Deploying Mule to Oracle Application Server

The following describes how to deploy the Mule JCA Resource Adapter Oracle application server allowing EJBs to send and receive Mule events and how to configure Mule to use Oracle Advanced queuing.

TODO. If you are using Mule with Oracle Application Server please contact us with your configuration and any tips to getting Oracle Application Server and Mule working together. Thanks!

Oracle Adnvaced Queuing (AQ) Configuration

There are some tricks to getting Oracle AQ working with Mule because the AQ implementation veers from the Jms specification when creating Connection Factories. The big difference is that Oracle uses a db-centric queue model meaning that really when you create a Connection you are creating a Oracle Jdbc connection. This connector will let Mule talk via the Jms API to a queue in an oracle database without using Jndi. (oracle standard edition disables exporting a queue to a repository).
This connector can be used to send a jms message when table data changes.

The Oracle JMS Provider extends the standard Mule Jms Provider with functionality specific to Oracle's JMS implementation based on Advanced Queueing (Oracle AQ).

The javadoc for this transport provider can be found here. And the Source Xref can be found here.

The Oracle JMS Provider adds support for queues with ADT (Advanced Data Type) payloads, including Oracle's native XML data type

Unlike the standard JMS Provider, the Oracle JMS Provider does not require a JNDI provider to use.

As of Oracle 9i, only the JMS 1.0.2b specification is supported.

Properties

In addition to the properties available for the standard Jms Provider, the Oracle JMS Provider adds the following properties:

Property	Description	Default	Required
url	The JDBC URL for the Oracle database, for example jdbc:oracle:oci:@myhost. The user and password may be specified in the URL itself, for example jdbc:oracle:oci:scott/tiger@myhost, in which case the (standard JMS Provider) properties username and password are not required.		yes
multipleSessionsPerConnection	Some versions of Oracle do not support more than one JMS session per connection. In this case we need to open a new connection for each session to avoid the following error: JMS-106: Cannot have more than one open Session on a JMSConnection	false	no
payloadFactory	If the queue's payload is an ADT (Oracle Advanced Data Type), the appropriate payload factory must be specified in the endpoint's properties.		no

Transformers

In addition to the transformers available for the standard Jms Provider, the Oracle JMS Provider adds the following transformers, found in org.mule.vendor.oracle.jms.transformers.

The default transformers are the same as the standard JMS Provider (JMSMessageToObject and ObjectToJMSMessage).

Example Configuration

The following is an example configuration using the Oracle JMS Provider:

<mule-configuration id="TestConfiguration" version="1.0">
    <connector name="oracleJmsConnector" className="org.mule.providers.oracle.jms.OracleJmsConnector">
        <properties>
           <property name="url" value="jdbc:oracle:oci:@myhost" />
        <property name="username" value="scott" />
      <property name="password" value="tiger" />
  </properties>
    </connector>
    <transformers>
        <transformer name="StringToXMLMessage"
             className="org.mule.providers.oracle.jms.transformers.StringToXMLMessage"
             returnClass="oracle.jms.AdtMessage" />
        <transformer name="XMLMessageToString"
             className="org.mule.providers.oracle.jms.transformers.XMLMessageToString"
             returnClass="java.lang.String" />
    </transformers>
    <global-endpoints>
   <endpoint name="XmlQueue" address="oaq://XML_QUEUE" transformers="StringToXMLMessage" />
    </global-endpoints>
    <model name="Test Model">
        <mule-descriptor name="XML-Driven UMO" implementation="com.foo.MyUMO">
      <inbound-router>
                    <endpoint address="oaq://XML_QUEUE" transformers="XMLMessageToString">
              <properties>
                        <property name="payloadFactory" value="oracle.xdb.XMLTypeFactory" />
                </properties>
               </endpoint>
         </inbound-router>
        </mule-descriptor>
    </model>
</mule-configuration>

Endpoints

Oracle AQ endpoints are expressed in the same way as Jms endpoints except the protocol is different.

oaq://my.queue

or

oaq://topic:my.topic

You can define an Oracle AQ endpoint without declaring the connector (as shown above), by including all necessary information on the endpoint uri i.e.

oaq://XML_QUEUE?url=jdbc:oracle:oci:scott/tiger@myhost

Refer to the unit tests for more examples on how to use the provider.

Dependencies

The Oracle JMS Provider requires the following Oracle libraries, which should be included in your Oracle installation:

• ojdbc14.jar
• aqapi13.jar
• jmscommon.jar
• xdb.jar (only required for native XML support)
• xmlparserv2.jar (only required for native XML support)

These jars are included in the distribution.

Unit Tests

The unit tests consist of two test suites: UnitTestSuite.java and IntegrationTestSuite.java. Only the integration test suite requires a live Oracle database.
In order to run the integration tests, you must edit the settings in file src/test/java/org/mule/providers/oracle/jms/TestConfig.java according to your Oracle database.

The tests assume that your Oracle user has sufficient privileges to create and drop queues in the database.

Roadmap (TO DO)

• Internationalization of messages
• Test with Oracle 10g (has only been tested with Oracle 9i)
• Test with other ADT types (has only been tested with XMLType)
• Test with topics (has only been tested with queues)
• Test with Oracle JDBC Thin Driver (has only been tested with the OCI driver)
• Add XA support